Expand DocC: config-type reference, rebalances/events, error handling, observability#248
Open
ssikka100 wants to merge 9 commits into
Open
Expand DocC: config-type reference, rebalances/events, error handling, observability#248ssikka100 wants to merge 9 commits into
ssikka100 wants to merge 9 commits into
Conversation
Add documentation-extension files providing abstracts and overviews for KafkaConfig, KafkaConsumerConfig, and KafkaProducerConfig, which are generated from .gyb templates and had no type-level doc comments. Documents them without touching the generated sources.
Add an 'Observe rebalances' section to ConsumingMessages demonstrating makeConsumerWithEvents and iterating KafkaConsumerEvents (previously the events sequence was only linked, never shown), and curate the events entry point in Topics.
Add three standalone articles: HandlingErrors (where KafkaError surfaces and how to classify it), Observability (enabling swift-metrics gauges and the structured logging metadata the client attaches), and Migrating (moving off the deprecated Configuration types and commitSync). Link them from the landing page.
FranzBusch
reviewed
Jul 14, 2026
Contributor
|
@heckj Could you take a look at this as well? |
heckj
suggested changes
Jul 14, 2026
- KafkaConsumerConfig.md, KafkaProducerConfig.md: replace symbol link abstracts with narrative prose (heckj) - HandlingErrors.md: make abstract active voice (heckj) - Observability.md: rename to 'Observing Kafka clients' to match sibling gerunds; active voice; drop librdkafka jargon; parallel imperative heading 'Emit structured logs' (heckj) - Remove Migrating.md — belongs in 1.0 release notes, not DocC (FranzBusch)
heckj
approved these changes
Jul 15, 2026
ssikka100
changed the title
Adopts the Swift-standard DocC pattern used by swift-nio and swift-metrics: each article groups related articles under `### Articles` before functional symbol groups, and `KafkaConsumer` / `KafkaProducer` symbol extensions add functional topic groups so members render in curated buckets. Config-type extension files keep their prose abstracts and add inline `<doc:...>` links to the security and walkthrough articles.
Applies heckj's rule about keeping implementation-detail library names out of user-facing conceptual prose, extending it to the config extension files and namespace type.
Contributor
|
I think the commit bfdd4e8 is causing an issue with doc generation. The soundness check is failing, indicating an error with articles curated into a cycle. Very worth fixing that up prior to merging, or SPI (or other systems) likely won't be able to render the docs. |
Each article listed every sibling under a Topics '### Articles' group, which DocC treats as a curation edge in the documentation hierarchy. The mutual references formed cycles (Observability -> HandlingErrors -> Observability, etc.), producing warnings on the Documentation soundness check. The landing page's Essentials group is now the sole curator of articles; inline <doc:...> links in each article's prose already provide cross-navigation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The DocC catalog added in #240 covers the core produce/consume/secure flow well, but several capabilities the client actually ships had no narrative documentation, the three generated configuration types had no type-level abstracts, and there was no curated organization for members of
KafkaConsumer/KafkaProducer.Modifications
KafkaConsumerandKafkaProducerprovide prose abstracts, an overview that points at the walkthrough article, and functional topic groups (creating, sending/consuming, running the service, offsets, subscriptions, pausing, seeking, observing events).KafkaConfig,KafkaConsumerConfig, andKafkaProducerConfig, with inline<doc:...>links from each config type toSecuringConnectionsand the relevant walkthrough article.ConsumingMessagesdemonstratesmakeConsumerWithEvents(config:logger:)and iteratingKafkaConsumerEvents(previously the events sequence was only linked, never shown), covering assign/revoke/error and cooperative vs eager assignment.KafkaErrorsurfaces (thrown, event sequences, delivery reports) and how to classify it withisFatal/isRetriable/rdKafkaCode.ConsumerMetrics/ProducerMetrics) and the structured logging metadata the client attaches (kafka.client.id,kafka.client.type,kafka.group.id). Delivers the observability integration the landing page advertises.### Articlesgroup at the top of## Topics, mirroring the pattern used by swift-nio and swift-metrics.Result
The DocC build is warning-free, the advertised-but-undocumented features (events sequence, error semantics, metrics, logging) now have guides, and
KafkaConsumer/KafkaProducerrender with curated topic groups so readers can navigate members by responsibility.